SGI Performance Co-Pilot 1.3

home *** CD-ROM | disk | FTP | other *** search

/ SGI Performance Co-Pilot 1.3 / SGI Performance Co-Pilot 1.3.iso / dist / dist6.4 / pcp.idb / usr / share / catman / u_man / cat3 / PMAPI / pmapi.z / pmapi

Wrap

Text File | 1997-04-03 | 30KB | 529 lines

PPPPMMMMAAAAPPPPIIII((((3333)))) PPPPMMMMAAAAPPPPIIII((((3333)))) NNNNAAAAMMMMEEEE PPPPMMMMAAAAPPPPIIII - introduction to the Performance Metrics Application Programming Interface CCCC SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS ####iiiinnnncccclllluuuuddddeeee <<<<ppppccccpppp////ppppmmmmaaaappppiiii....hhhh>>>> ... assorted routines ... cccccccc ............ ----llllppppccccpppp DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN Within the framework of the Performance Co-Pilot (PCP), client applications are developed using the Performance Metrics Application Programming Interface (PMAPI) that defines a procedural interface with services suited to the development of applications with a particular interest in performance metrics. This description presents an overview of the PMAPI and the context in which PMAPI applications are run. The PMAPI is more fully described in in the _P_e_r_f_o_r_m_a_n_c_e _C_o-_P_i_l_o_t _P_r_o_g_r_a_m_m_e_r'_s _G_u_i_d_e, and the manual pages for the individual PMAPI routines. PPPPEEEERRRRFFFFOOOORRRRMMMMAAAANNNNCCCCEEEE MMMMEEEETTTTRRRRIIIICCCCSSSS ---- NNNNAAAAMMMMEEEESSSS AAAANNNNDDDD IIIIDDDDEEEENNNNTTTTIIIIFFFFIIIIEEEERRRRSSSS The number of performance metric types is of the order of a few thousand. The PMAPI uses an internal identification scheme that unambiguously associates a single integer with each of the known types of performance metric. This integer is known as the Performance Metric Identifier, or PMID. PMIDs have global consistency across all systems, so a particular performance metric universally has the same PMID. For many applications, direct use of the PMIDs may be inappropriate (e.g. this would limit the range of accessible metrics, make the code hard to maintain, force the user interface to be particularly baroque, etc.). Hence above the PMAPI, a Performance Metrics Name Space (PMNS) is used to provide a hierarchic classification of PMIDs. A PMNS is represented as a tree, with each node having a label, a pointer to either a PMID (for leaf nodes) or a set of descendent nodes in the PMNS (for non-leaf nodes). A node label must begin with an alphabetic character, followed by zero or more characters drawn from the alphabetics, the digits and character `_' (underscore). For alphabetic characters in a node label, upper and lower case are distinguished. By convention, the name of a performance metric is constructed by concatenation of the node labels on a path through the PMNS from the root node to a leaf node, with a ``.'' as a separator. The root node in the PMNS is unlabelled, so all names begin with the label associated with one of the descendent nodes below the root node of the PMNS, e.g. _i_r_i_x._k_e_r_n_e_l._p_e_r_c_p_u._s_y_s_c_a_l_l. There may be at most one name for each PMID in a PMNS. For example _i_r_i_x._k_e_r_n_e_l._a_l_l._c_p_u._i_d_l_e and _i_r_i_x._d_i_s_k._d_e_v._r_e_a_d are the unique names for two distinct performance metrics, each with a PPPPaaaaggggeeee 1111 PPPPMMMMAAAAPPPPIIII((((3333)))) PPPPMMMMAAAAPPPPIIII((((3333)))) unique PMID. Groups of related PMIDs may be named by naming a non-leaf node in the PMNS tree, e.g. _i_r_i_x._d_i_s_k. Use ppppmmmmiiiinnnnffffoooo(1), or the Metric Selection browser within ppppmmmmcccchhhhaaaarrrrtttt(1) to explore the PMNS. There may be PMIDs with no associated name in a PMNS; this is most likely to occur when specific PMIDs are not available in all systems, e.g. if Informix is not installed on a system, there is no good reason to pollute the PMNS with names for all of the Informix performance metrics. Applications which use the PMAPI may have independent versions of a PMNS, constructed from an initialization file when the application starts; see ppppmmmmLLLLooooaaaaddddAAAASSSSCCCCIIIIIIIINNNNaaaammmmeeeeSSSSppppaaaacccceeee(3), ppppmmmmLLLLooooaaaaddddNNNNaaaammmmeeeeSSSSppppaaaacccceeee(3), ppppmmmmnnnnssssccccoooommmmpppp(1) and ppppmmmmnnnnssss(4). Not all PMIDs need be represented in the PMNS of every application. For example, an application which monitors disk traffic will likely use a name space which references only the PMIDs for I/O statistics. Note also that there is no requirement for the PMNS to be the same on all systems, however in practice most applications would be developed against a stable PMNS that was assumed to be the same on all systems. Indeed the PCP distribution includes a default PMNS for just this purpose. The default PMNS is located at /_v_a_r/_p_c_p/_p_m_n_s/_r_o_o_t for base PCP installations, however the environment variable PPPPMMMMNNNNSSSS____DDDDEEEEFFFFAAAAUUUULLLLTTTT may be set to the full pathname of a different PMNS which will then be used as the default PMNS. Other complete versions of the PMNS suitable for assorted variants on the base PCP installation may be found in the files /_v_a_r/_p_c_p/_p_m_n_s/_r_o_o_t_*. For some PCP deployments on non-SGI platforms, the PMNS may be different, and in some cases very diffent. Where possible, a hybrid PMNS that provides equivalence mappings between the IRIX names and the non-SGI PMIDs may be found in the files /_v_a_r/_p_c_p/_p_m_n_s/_e_q_u_i_v_*. Internally (below the PMAPI) the implementation of the Performance Metrics Collection System (PMCS) uses only the PMIDs, and a PMNS provides an external mapping from a hierarchic taxonomy of names to PMIDs that is convenient in the context of a particular system or particular use of the PMAPI. For the applications programmer, the routines ppppmmmmLLLLooooooookkkkuuuuppppNNNNaaaammmmeeee(3) and ppppmmmmNNNNaaaammmmeeeeIIIIDDDD(3) translate between names in a PMNS and PMIDs, and vice versa. The PMNS may be traversed using ppppmmmmGGGGeeeettttCCCChhhhiiiillllddddrrrreeeennnn(3). PPPPMMMMAAAAPPPPIIII CCCCOOOONNNNTTTTEEEEXXXXTTTT An application using the PMAPI may manipulate several concurrent contexts, each associated with a source of performance metrics, e.g. ppppmmmmccccdddd(1) on some host, or an archive log of performance metrics as created by ppppmmmmllllooooggggggggeeeerrrr(1). PPPPaaaaggggeeee 2222 PPPPMMMMAAAAPPPPIIII((((3333)))) PPPPMMMMAAAAPPPPIIII((((3333)))) Contexts are identified by a ``handle'', a small integer value that is returned when the context is created; see ppppmmmmNNNNeeeewwwwCCCCoooonnnntttteeeexxxxtttt(3) and ppppmmmmDDDDuuuuppppCCCCoooonnnntttteeeexxxxtttt(3). Some PMAPI functions require an explicit ``handle'' to identify the correct context, but more commonly the PMAPI function is executed in the ``current'' context. The current context may be discovered using ppppmmmmWWWWhhhhiiiicccchhhhCCCCoooonnnntttteeeexxxxtttt(3) and changed using ppppmmmmUUUUsssseeeeCCCCoooonnnntttteeeexxxxtttt(3). If a PMAPI context has not been explicitly established (or the previous current context has been closed using ppppmmmmDDDDeeeessssttttrrrrooooyyyyCCCCoooonnnntttteeeexxxxtttt(3)) then the current PMAPI context is undefined. In addition to the source of the performance metrics, the context also includes the instance profile and collection time (both described below) which controls how much information is returned, and when the information was collected. IIIINNNNSSSSTTTTAAAANNNNCCCCEEEE DDDDOOOOMMMMAAAAIIIINNNNSSSS When performance metric values are returned across the PMAPI to a requesting application, there may be more than one value for a particular metric. Multiple values, or iiiinnnnssssttttaaaannnncccceeeessss, for a single metric are typically the result of instrumentation being implemented for each instance of a set of similar components or services in a system, e.g. independent counts for each CPU, or each process, or each disk, or each system call type, etc. This multiplicity of values is not enumerated in the name space but rather, when performance metrics are delivered across the PMAPI by ppppmmmmFFFFeeeettttcccchhhh(3), the format of the result accommodates values for one or more instances, with an instance-value pair encoding the metric value for a particular instance. The instances are identified by an internal identifier assigned by the agent responsible for instantiating the values for the associated performance metric. Each instance identifier has a corresponding external instance identifier name (an ASCII string). The routines ppppmmmmGGGGeeeettttIIIInnnnDDDDoooommmm(3), ppppmmmmLLLLooooooookkkkuuuuppppIIIInnnnDDDDoooommmm(3) and ppppmmmmNNNNaaaammmmeeeeIIIInnnnDDDDoooommmm(3) may be used to enumerate all instance identifiers, and to translate between internal and external instance identifiers. All of the instance identifiers for a particular performance metric are collectively known as an instance domain. Multiple performance metrics may share the same instance domain. If only one instance is ever available for a particular performance metric, the instance identifier in the result from ppppmmmmFFFFeeeettttcccchhhh(3) assumes the special value PPPPMMMM____IIIINNNN____NNNNUUUULLLLLLLL and may be ignored by the application, and only one instance-value pair appears in the result for that metric. Under these circumstances, the associated instance domain (as returned via ppppmmmmLLLLooooooookkkkuuuuppppDDDDeeeesssscccc(3)) is set to PPPPMMMM____IIIINNNNDDDDOOOOMMMM____NNNNUUUULLLLLLLL to indicate that values for this metric are singular. The difficult issue of transient performance metrics (e.g. per-filesystem information, hot-plug replaceable hardware modules, etc.) means that repeated requests for the same PMID may return different numbers of PPPPaaaaggggeeee 3333 PPPPMMMMAAAAPPPPIIII((((3333)))) PPPPMMMMAAAAPPPPIIII((((3333)))) values, and/or some changes in the particular instance identifiers returned. This means applications need to be aware that metric instantiation is guaranteed to be valid at the time of collection only. Similar rules apply to the transient semantics of the associated metric values. In general however, it is expected that the bulk of the performance metrics will have instantiation semantics that are fixed over the execution life-time of any PMAPI client. TTTTHHHHEEEE TTTTYYYYPPPPEEEE OOOOFFFF MMMMEEEETTTTRRRRIIIICCCC VVVVAAAALLLLUUUUEEEESSSS The PMAPI supports a wide range of format and type encodings for the values of performance metrics, namely signed and unsigned integers, floating point numbers, 32-bit and 64-bit encodings of all of the above, ASCII strings (C-style, NULL byte terminated), and arbitrary aggregates of binary data. The _t_y_p_e field in the _p_m_D_e_s_c structure returned by ppppmmmmLLLLooooooookkkkuuuuppppDDDDeeeesssscccc(3) identifies the format and type of the values for a particular performance metric within a particular PMAPI context. Note that the encoding of values for a particular performance metric may be different for different PMAPI contexts, due to differences in the underlying implementation for different contexts. However it is expected that the vast majority of performance metrics will have consistent value encoding across all versions of all implementations, and hence across all PMAPI contexts. The PMAPI supports routines to automate the handling of the various value formats and types, particularly for the common case where conversion to a canonical format is desired, see ppppmmmmEEEExxxxttttrrrraaaaccccttttVVVVaaaalllluuuueeee(3) and ppppmmmmPPPPrrrriiiinnnnttttVVVVaaaalllluuuueeee(3). TTTTHHHHEEEE DDDDIIIIMMMMEEEENNNNSSSSIIIIOOOONNNNAAAALLLLIIIITTTTYYYY AAAANNNNDDDD SSSSCCCCAAAALLLLEEEE OOOOFFFF MMMMEEEETTTTRRRRIIIICCCC VVVVAAAALLLLUUUUEEEESSSS Independent of how the value is encoded, the value for a performance metric is assumed to be drawn from a set of values that can be described in terms of their dimensionality and scale by a compact encoding as follows. The dimensionality is defined by a power, or index, in each of 3 orthogonal dimensions, namely Space, Time and Count (or Events, which are dimensionless). For example I/O throughput might be represented as Space.Time-1, while the running total of system calls is Count, memory allocation is Space and average service time is Time.Count-1. In each dimension there are a number of common scale values that may be used to better encode ranges that might otherwise exhaust the precision of a 32- bit value. This information is encoded in the _p_m_U_n_i_t_s structure which is embedded in the _p_m_D_e_s_c structure returned from ppppmmmmLLLLooooooookkkkuuuuppppDDDDeeeesssscccc(3). The routine ppppmmmmCCCCoooonnnnvvvvSSSSccccaaaalllleeee(3) is provided to convert values in conjunction with the _p_m_U_n_i_t_s structures that defines the dimensionality and scale of the values for a particular performance metric as returned from ppppmmmmFFFFeeeettttcccchhhh(3), and the desired dimensionality and scale of the value the PMAPI client wishes to manipulate. PPPPaaaaggggeeee 4444 PPPPMMMMAAAAPPPPIIII((((3333)))) PPPPMMMMAAAAPPPPIIII((((3333)))) IIIINNNNSSSSTTTTAAAANNNNCCCCEEEE PPPPRRRROOOOFFFFIIIILLLLEEEE The set of instances for performance metrics returned from a ppppmmmmFFFFeeeettttcccchhhh(3) call may be filtered or restricted using an instance profile. There is one instance profile for each PMAPI context the application creates, and each instance profile may include instances from one or more instance domains. The routines ppppmmmmAAAAddddddddPPPPrrrrooooffffiiiilllleeee(3) and ppppmmmmDDDDeeeellllPPPPrrrrooooffffiiiilllleeee(3) may be used to dynamically adjust the instance profile. CCCCOOOOLLLLLLLLEEEECCCCTTTTIIIIOOOONNNN TTTTIIIIMMMMEEEE For each set of values for performance metrics returned via ppppmmmmFFFFeeeettttcccchhhh(3) there is an associated ``timestamp'' that serves to identify when the performance metric values were collected; for metrics being delivered from a real-time source (i.e. ppppmmmmccccdddd(1) on some host) this would typically be not long before they were exported across the PMAPI, and for metrics being delivered from an archive log, this would be the time when the metrics were written into the archive log. There is an issue here of exactly when individual metrics may have been collected, especially given their origin in potentially different Performance Metric Domains, and variability in the metric updating frequency at the lowest level of the Performance Metric Domain. The PMCS opts for the pragmatic approach, in which the PMAPI implementation undertakes to return all of the metrics with values accurate as of the timestamp, to the best of our ability. The belief is that the inaccuracy this introduces is small, and the additional burden of accurate individual timestamping for each returned metric value is neither warranted nor practical (from an implementation viewpoint). Of course, in the case of collection of metrics from multiple hosts the PMAPI client must assume the sanity of the timestamps is constrained by the extent to which clock synchronization protocols are implemented across the network. A PMAPI application may call ppppmmmmSSSSeeeettttMMMMooooddddeeee(3) to vary the requested collection time, e.g. to rescan performance metrics values from the recent past, or to ``fast-forward'' through an archive log. GGGGEEEENNNNEEEERRRRAAAALLLL IIIISSSSSSSSUUUUEEEESSSS OOOOFFFF PPPPMMMMAAAAPPPPIIII PPPPRRRROOOOGGGGRRRRAAAAMMMMMMMMIIIINNNNGGGG SSSSTTTTYYYYLLLLEEEE Across the PMAPI, all arguments and results involving a ``list of something'' are declared to be arrays with an associated argument or function value to identify the number of elements in the list. This has been done to avoid both the vvvvaaaarrrraaaarrrrggggssss(3) approach and sentinel-terminated lists. Where the size of a result is known at the time of a call, it is the caller's responsibility to allocate (and possibly free) the storage, and the called function will assume the result argument is of an appropriate size. Where a result is of variable size and that size cannot be known in advance (e.g. for ppppmmmmGGGGeeeettttCCCChhhhiiiillllddddrrrreeeennnn(3), ppppmmmmGGGGeeeettttIIIInnnnDDDDoooommmm(3), ppppmmmmNNNNaaaammmmeeeeIIIInnnnDDDDoooommmm(3), ppppmmmmNNNNaaaammmmeeeeIIIIDDDD(3), ppppmmmmLLLLooooooookkkkuuuuppppTTTTeeeexxxxtttt(3) and ppppmmmmFFFFeeeettttcccchhhh(3)) the PMAPI implementation PPPPaaaaggggeeee 5555 PPPPMMMMAAAAPPPPIIII((((3333)))) PPPPMMMMAAAAPPPPIIII((((3333)))) uses a range of dynamic allocation schemes in the called routine, with the caller responsible for subsequently releasing the storage when no longer required. In some cases this simply involves calls to ffffrrrreeeeeeee(3C), but in others (most notably for the result from ppppmmmmFFFFeeeettttcccchhhh(3)), special routines (e.g. ppppmmmmFFFFrrrreeeeeeeeRRRReeeessssuuuulllltttt(3)) should be used to release the storage. As a general rule, if the called routine returns an error status then no allocation will have been done, and any pointer to a variable sized result is undefined. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS Where error conditions may arise, the functions that comprise the PMAPI conform to a single, simple error notification scheme, as follows; + the function returns an integer + values >= 0 indicate no error, and perhaps some positive status, e.g. the number of things really processed + values < 0 indicate an error, with a global table of error conditions and error messages The PMAPI routine ppppmmmmEEEErrrrrrrrSSSSttttrrrr(3) translates error conditions into error messages. By convention, the small negative values are assumed to be negated versions of the Unix error codes as defined in <<<<eeeerrrrrrrrnnnnoooo....hhhh>>>> and the strings returned are as per ssssttttrrrreeeerrrrrrrroooorrrr(3C). The larger, negative error codes are PMAPI error conditions. One error, common to all PMAPI routines that interact with ppppmmmmccccdddd(1) on some host is PPPPMMMM____EEEERRRRRRRR____IIIIPPPPCCCC, which indicates the communication link to ppppmmmmccccdddd(1) has been lost. EEEENNNNVVVVIIIIRRRROOOONNNNMMMMEEEENNNNTTTT The TPC/IP port used by ppppmmmmccccdddd(1) to create the socket for incoming connections and requests, is by default port number 4321. This may be over-ridden by setting PPPPMMMMCCCCDDDD____PPPPOOOORRRRTTTT to a different port number. If a non- default port is used when ppppmmmmccccdddd(1) is started, then every monitoring application connecting to that ppppmmmmccccdddd(1) must also have PPPPMMMMCCCCDDDD____PPPPOOOORRRRTTTT set in their environment before attempting a connection. When attempting to connect to a remote ppppmmmmccccdddd(1) on a machine that is booting, some PMAPI routines could potentially block for a long time until the remote machine finishes its initialisation. These routines will abort and return an error if the connection has not been established after some specified interval has elapsed. The default interval is 5 seconds. This may be modified by setting PPPPMMMMCCCCDDDD____CCCCOOOONNNNNNNNEEEECCCCTTTT____TTTTIIIIMMMMEEEEOOOOUUUUTTTT in the environment to a real number of seconds for the desired timeout. This is most useful in cases where the remote host is at the end of a slow network, requiring longer latencies to establish the connection correctly. PPPPaaaaggggeeee 6666 PPPPMMMMAAAAPPPPIIII((((3333)))) PPPPMMMMAAAAPPPPIIII((((3333)))) When a monitor or client application loses a connection to a ppppmmmmccccdddd(1), the connection may be re-established by calling the PMAPI function ppppmmmmRRRReeeeccccoooonnnnnnnneeeeccccttttCCCCoooonnnntttteeeexxxxtttt(1). However, attempts to reconnect are controlled by a back-off strategy to avoid flooding the network with reconnection requests. By default, the back-off delays are 5, 10, 20, 40 and 80 seconds for consecutive reconnection requests from a client (the last delay will be repeated for any further attempts after the fifth). Setting the environment variable PPPPMMMMCCCCDDDD____RRRREEEECCCCOOOONNNNNNNNEEEECCCCTTTT____TTTTIIIIMMMMEEEEOOOOUUUUTTTT to a comma separated list of positive integers will re-define the back-off delays, e.g. setting PPPPMMMMCCCCDDDD____RRRREEEECCCCOOOONNNNNNNNEEEECCCCTTTT____TTTTIIIIMMMMEEEEOOOOUUUUTTTT to ``1,2'' will back-off for 1 second, then attempt another connection request every 2 seconds thereafter. For monitor or client applications connected to ppppmmmmccccdddd(1), there is a possibility of the application "hanging" on a request for performance metrics or metadata or help text. These delays may become severe if the system running ppppmmmmccccdddd crashes, or the network connection is lost. By setting the environment variable PPPPMMMMCCCCDDDD____RRRREEEEQQQQUUUUEEEESSSSTTTT____TTTTIIIIMMMMEEEEOOOOUUUUTTTT to a real number of seconds, requests to ppppmmmmccccdddd will timeout after this number of seconds. The default behaviour is to be willing to wait 10 seconds for a response from every ppppmmmmccccdddd for all applications. Many of the PMAPI client programs require that a valid software license be present on the host on which the client is running (the license is node-locked). In the case that such a valid license is present, but is due to expire within the next 30 days, a message or popup notifier appears informing the user of this condition. These warnings can be disabled by setting PPPPCCCCPPPP____LLLLIIIICCCCEEEENNNNCCCCEEEE____NNNNOOOOWWWWAAAARRRRNNNNIIIINNNNGGGG in the environment. The environment variable PPPPMMMMLLLLOOOOGGGGGGGGEEEERRRR____PPPPOOOORRRRTTTT may be used to change the base TCP/IP port number used by ppppmmmmllllooooggggggggeeeerrrr(1) to create the socket to which ppppmmmmllllcccc(1) instances will try and connect. The default base port number is 4330. When used, PPPPMMMMLLLLOOOOGGGGGGGGEEEERRRR____PPPPOOOORRRRTTTT should be set in the environment before ppppmmmmllllooooggggggggeeeerrrr(1) is executed. Many PCP utilites create diagnostic and trace log files, and the default locations are below the directory /_v_a_r/_a_d_m/_p_c_p_l_o_g. Setting the environment variable PPPPCCCCPPPP____LLLLOOOOGGGGDDDDIIIIRRRR will over-ride the default choice of directory. If PPPPCCCCPPPP____LLLLOOOOGGGGDDDDIIIIRRRR is unset, the environment variable PPPPCCCCPPPPLLLLOOOOGGGGDDDDIIIIRRRR will be treated as an alias and used if set (this provides backwards compatibility with earlier PCP releases). Many of the performance metrics exported from PCP agents have the semantics of _c_o_u_n_t_e_r meaning they are expected to be monotonically increasing. Under some circumstances, one value of these metrics may smaller than the previously fetched value. This can happen when a counter of finite precision overflows, or when the PCP agent has been reset or restarted, or when the PCP agent is exporting values from some underlying instrumentation that is subject to some asynchronous discontinuity. PPPPaaaaggggeeee 7777 PPPPMMMMAAAAPPPPIIII((((3333)))) PPPPMMMMAAAAPPPPIIII((((3333)))) The environment variable PPPPCCCCPPPP____CCCCOOOOUUUUNNNNTTTTEEEERRRR____WWWWRRRRAAAAPPPP may be set to indicate that all such cases of a decreasing ``counter'' should be treated as a counter overflow, and hence the values are assumed to have wrapped once in the interval between consecutive samples. This ``wrapping'' behavior was the default in earlier PCP versions, but by default has been disabled in PCP 1.3. PPPPaaaaggggeeee 8888